Copyright: Copyright © 1998 Rational Software Corporation. All rights reserved.


Changing the Appearance of the Synchronizer

You can change the appearance of the Synchronizer as follows:

Change pane size.
You can change the size of the Synchronizer panes. Place the cursor on a border between two panes. The cursor changes to a double-arrow. Drag the border until the pane is the size that you want.

Display or hide toolbar and status bar.
Toggle whether the toolbar and status bar are displayed or hidden by making a selection from the View menu.


Creating a Rule

This task is typically performed by an administrator or an advanced user.

To create Synchronizer rules:

1.	Either open an existing rule file

OR create an ASCII text file with an extension of .rsd. We recommend that you name rule files to reflect the purpose of the rule or rules they contain.

2.	Add text to define the rule.

3.	Import the new rule into the Synchronizer.

For information about rule syntax, see Rational Suite Usage Notes.

See also: Tips for Working with Rules


Disabling or Enabling an Item

Disabling an Item

To disable an item (prevent it from synchronizing):

1.	In the Item List, select the item or items that you want to disable. To select more than one item, press the CTRL or SHIFT button while you click.

2.	Choose Actions > Disable Selected Items.

The item's state changes to Disabled. You cannot synchronize an item when its state is Disabled.

Enabling an Item

To enable an item (allow a disabled item to synchronize):

1.	Select the item or items that you want to enable. To select more than one item, press the CTRL or SHIFT button while you click.

2.	Choose Actions > Enable Selected Items.

The item's state changes to Pending. You cannot synchronize an item unless its state is Pending.


Editing a Rule

This task is typically performed by an administrator or an advanced user.

To edit an existing rule:

1.	Use Notepad to open the text file containing the rule. The file has an extension of .rsd.

2.	Modify the rule and save the file.

3.	Import the rule file into the project. When you are asked whether you want to replace existing rules of the same name, click Yes.

For information about rule syntax, see Rational Suite Usage Notes.

See also:Tips for Working with Rules


Examples of Using the Synchronize Wizard
Examples of Using the Synchronizer Find Wizard

The following examples describe working with the Synchronizer Find Wizard:

You are a team member working on a use case in Rose. You are in the middle of the project when you decide to make your changes so far available to other workers. You also want to incorporate recent changes into your use case before you continue work. Use the Synchronizer Find Wizard to Search for a subset of items. Pick a Rose Use Case and pick Synchronize (that is, you broadcast changes from the Use Cases and cause the Use Cases to receive changes from other items).

You are a member of the QE team. You are working on test requirements but you've heard that an analyst has changed the software requirements for your project. You want to include those changes into the test requirements you are working on. Use the Synchronizer Find Wizard to Search using selected rules. Pick a rule that transfers information from RequisitePro software requirements to Test Studio test requirements.

You are a project leader. This Friday, your project meets its deadline for the end of a development iteration. On Friday afternoon, you synchronize, choosing Search all projects. When team members come to work on Monday, they start work on the next iteration with the newly updated items.


Getting Information about a Rule

To get details about a rule:

1.	In the  Item List of the Synchronizer, select an action whose associated rule you want information about.

2.	In the Item Details, click the Rule tab.

The Item Details displays information about the rule.


What Do I Do First?

If you have not yet started the Synchronizer, read Starting the Synchronizer.

Typical Session

In a typical Synchronizer session, you:

1.	Run the Synchronizer Find Wizard to find specific items to synchronize.

2.	Review the items found in Step 1. These items appear in the Item List.

3.	Select one or more items to synchronize.

4.	From the Synchronizer menu, choose Actions > Synchronize Selected Items.

See also: Disabling or enabling an item

Setting Up a Project

If you are an administrator or an advanced user, you may need to set up a project before users can synchronize items:

1.	If your users have installed Rational Suite, use the Rational Administrator to create a repository project.

2.	Edit existing sample rules or write your own rules to describe how synchronization should proceed on your project. (For more information, see Creating a rule, Tips for Working with Rules, and the manual, Rational Suite Usage Notes, available as a book and on the Rational Solutions for Windows - Online Documentation CD.

3.	Import the rules into the rules project so that the Synchronizer can use them.

4.	Save the rules project.

Your users are now ready to use the Synchronizer for your project.


Getting Information about an Item

Item Details provides information about the item selected in the Item List. (If you have selected more than one item, the detailed information refers to the item that appears first in the list.)


CONTENTS (Rational Synchronizer)
Rational Synchronizer

The Rational Synchronizer automates creating and updating items in your project. The Synchronizer works with items in RequisitePro (requirements), Rose (use cases and actors), and TestStudio (scripts).

The Synchronizer uses rules based on your development process to determine which items to create or update.

Examples and Benefits

For example, your project may have a rule that says "For every Rose use case, create a corresponding test requirement, if one does not already exist." You can enforce this relationship with a Synchronizer rule. When Rose use cases change, this rule communicates changes accurately and promptly to the team that is working on testing.

As another example, your project may want to create a test script in TestStudio for every test requirement. By using the Synchronizer, you ensure that changing project information does not slip through the cracks.

How to

Start the Synchronizer

What do I do first?

Use the Find Wizard

Work with the Synchronizer

Perform administrative tasks

Troubleshoot problems

For More Information

For more information about the Synchronizer, please see the manual, Rational Suite Usage Notes, available as a book and on the Rational Solutions for Windows - Online Documentation CD.


Updating Items

While using the Synchronizer, you may decide to update the Item List. For example, you may want to consider the effects of changes made since you started the Synchronizer. You have these choices:

Find Again

Refreshes the Item List, using the same criteria you last specified with the Find Wizard. Use this choice when rules or items have changed and you want to ensure that the Synchronizer is working with the latest information.

Rerun the Synchronizer Find Wizard

Displays the Synchronizer Find Wizard so that you can add to the items in the Item List. Use this choice to consider new items in addition to the current items in the Item List.


Synchronizing an Item

To synchronize one or more items:

1.	In the Item List, select the item or items that you want to synchronize. To select more than one item, hold down the CTRL or SHIFT button while you click.

2.	From the menu, choose Actions > Synchronize Selected Items.

Once an item is synchronized, its state changes from Pending to Complete.

Alternative

To synchronize all items in the Item List, from the menu, choose Actions > Synchronize All Items.

Problems?

If you encounter problems, please read about Troubleshooting.


Starting the Synchronizer

The following table shows how to start the Synchronizer:

From this tool	Choose from the menu
RequisitePro	Tools > Rational Synchronizer
Rose	Tools > Synchronize
Rational TestManager	Tools > Rational Synchronizer
Rational Administrator	Tools > Rational Synchronizer
Windows Start menu	Programs > Rational Suite > Rational Synchronizer
Startup Context

The Synchronizer determines whether it can identify the rules project to use.

Synchronizer Identifies the Rules Project

If you have installed Rational Suite, your project administrator has probably used the Rational Administrator to define a repository project for your team. Defining a repository project automatically creates a default rules project. In this simplest case, if you start the Synchronizer from RequisitePro, Rose, or TestManager, the Synchronizer Find Wizard appears.

You Select the Repository Project: Setup Context Dialog Box

In some cases, you might start the Synchronizer from a context in which the Synchronizer cannot identify the rules project to use. In this case, the Synchronizer displays a Setup Context dialog box.

1.	If Rational Suite is installed, then click Synchronize a Rational Repository Project.

A Rational Repository Login dialog box appears.

2.	Supply your User ID, password, the path of the repository, and the project name. Click OK.

The Synchronizer Find Wizard appears.

No Repository Project; Work directly with a Rules Project: Setup Context Dialog Box

If you are not using Rational Suite, you need to identify the rules project to use each time you start the Synchronizer:

1.	In the Setup Context dialog box, click Synchronize without using the Rational Repository.

2.	If you have already created a rules project, click Open an existing Synchronizer Rules Project and click OK. A dialog box appears prompting you to select the rules project.

3.	If you have not yet created a rules project, click Create a Synchronizer Rules Project and click OK. A dialog box appears prompting you to name the new rules project. The new rules project is empty. To add rules, import them.


Synchronizer Find Wizard

The Synchronizer Find Wizard helps you narrow the scope of items to update in your development environment. For example, there may be hundreds or thousands of items in your project. By using the Find Wizard, you can focus on a subset of items to work with.

Examples

For example, you can use the Find Wizard to:

Find all the Rose use cases that need to be updated.

Here's how	On the Type of search page, select Search for a subset of items. On the Select items to Synchronize page, expand Rose and select Use Case. (Depending on your project, this option may not be available.) On the Select synchronization flow page, select Receive (you want Rose to receive the changes).
Find all Rose Actors that need to be created when a corresponding RequisitePro actor exists.

Here's how	On the Type of search page, select Search using selected rules. On the Choose Rules page, select the rule to use. For this example, select Rose actor from RequisitePro ACTOR. (This is a sample rule; it may not be available for your project.)
Find all items in your project that need updating.

Here's how	On the Type of search page, select Search all projects.
After you Use the Synchronizer Find Wizard

When you finish using the Synchronizer Find Wizard, the Item List in the Synchronizer displays the items that need synchronizing. You can select the exact set of items to synchronize.

How Does the Synchronizer Work?

The Synchronizer uses rules to link related items. One rule might be paraphrased as follows: "For every software requirement in RequisitePro, there must be a corresponding test requirement in Test Studio". The Synchronizer has a predefined set of rules. Someone, usually an administrator, can customize the rules that your project uses.

Examples


Working with Items

The Item List displays the results of using the Find Wizard. Each item listed represents a change you can make to the project you are working on. Each item has a state.

Items can have one of two associated actions:

Create makes a new item.

Update edits the values of an existing item.

See also:

Synchronizing an Item

Disabling or enabling an action

Getting more information about an item

Updating the Item List


Working with Rules

A rule describes a set of changes to make and the conditions under which to make the changes. For example, a rule might say that for every use case specification in RequisitePro, create a corresponding use case in Rose.

The Synchronizer comes with a set of predefined rules, which may serve your project well. If you decide to add, edit, or delete a rule, make sure that you coordinate the change with other members of your project, because the changes will affect the entire project.

Get more information about a rule

Administrative tasks:

Create a rule

Edit a rule

Delete a rule

See also:Tips for Working with Rules


Working with the Synchronizer

The following topics describe the Synchronizer layout and how to get the most out of the Synchronizer:

Understanding the Synchronizer layout

Changing the appearance of the Synchronizer

Using the Synchronizer Find Wizard

Working with Items

Working with Rules


Using the Synchronizer to Create a Rules Project

A rules project associates a set of rules with domain projects.

If Rational Suite is installed on your system, we recommend that you use Rational Administrator to create rules projects. Otherwise, create a rules project when you start the Synchronizer:

1.	From the Windows Start menu, choose Programs > Rational Suite > Rational Synchronizer.

The Synchronizer displays the Setup Context dialog box.

2.	Click Synchronize without using the Rational Repository, then click Create a Synchronizer Rules Project. Click OK.

3.	Use the Create Synchronizer Rules Project dialog box to specify a name and location for the rules project. Click Save.

Note: We recommend that you maintain rules project files under source control.

4.	The Synchronizer asks "Would you like to import rule definitions?"

Click Yes to associate rules with the rules project.
Click No to leave the rules project without any rules associated with it.

5.	If you click Yes, the Synchronizer displays the Import Rules dialog box. Select the rules file (a file with extension .rsd) to import. Click Open.

6.	The Synchronizer prompts you to add one or more domain projects to the rules project.

7.	The Synchronizer prompts you to save changes.


Importing Rules

This task is typically performed by an administrator or an advanced user.

After you create a rule, import the file into a rules project as follows:

1.	From the Synchronizer menu, choose File > Import Rules.

2.	In the Import rules dialog box, browse to and select the file containing rules to import.

The predefined rules for Rational Suite are in
install\Rational\common\OutOfTheBox\synchronizer rules, where install is the directory where you installed Rational Suite, by default c:\Program Files.

3.	Click Open.

See Replacing Rules, below, if you are prompted about replacing a rule.

The Synchronizer saves your rules project.

4.	The Synchronizer asks if you want to search for items to synchronize. Click Yes to start the Find Wizard and have it use the new rule. Click No to leave the Item List blank, with no items listed. You can run the Find Wizard at any time to repopulate the Item List.

The Synchronizer includes the rule, in a compiled format, in the rules project. If you change the text definition of the rule in the rules file, the changes do not affect the Synchronizer until you import the rule again.

Replacing Rules

If you are importing a rule with the same name as a rule that is already in your rules project, the Synchronizer displays a message asking whether to replace the existing rule:

Click Yes to continue importing the rule (overwriting the existing rule).

Click No to skip importing this rule and go on to the next rule.

Click Cancel to skip importing this rule and all remaining rules.

See also Tips for Working with Rules.


Synchronizer Layout

The Synchronizer is arranged as follows. Click on parts of the picture for more information:


Deleting a Rule

This task is typically performed by an administrator or an advanced user.

1.	From the Synchronizer menu, choose File > Delete Rules.

The Synchronizer presents a list of rules.

2.	From the list, select one or more rules to delete.

3.	Click OK.

The Synchronizer deletes the rule from the current rules project. It does not delete the text version of the rule in the rules file.


Perform Administrative Tasks

The following tasks are typically performed by an administrator or by an advanced user:

Create a rule to add to the set of existing rules.

Edit a rule to change an existing rule.

Import rules to allow this project access to an additional set of rules.

Delete a rule to remove a rule from this project.

Create a rules project to collect and manage rules.


Item States

The Synchronizer Item List contains a column for the state of each item:

State	Meaning
Pending	An item that is ready to be synchronized.
Disabled	An item that you have explicitly prevented from being synchronized.
Complete	An item that you have already synchronized in the current session.
None	No action needed at this time.


Using Rational Administrator to Create a Rules Project
Using Rational Administrator to Create a Repository Project

Use the Rational Administrator to create a repository project. A repository project associates sets of rules with Rational Suite domain projects. For example, you can create a repository project that associates:

A Rational Test script database

A Rational ClearQuest defect database

A RequisitePro project

One or more Rose models

A Synchronizer rules project

For more information, read about projects, adding in the Rational Administrator help.

Once you create a repository project, use the Rational Administrator to run the Synchronizer (from the menu, choose Tools > Rational Synchronizer). In the Synchronizer, indicate which rules to use when synchronizing this project by importing rules into the project.

Once you create this project, the Synchronizer Find Wizard can start automatically without prompting you to specify the rules to use.


Domain Project

A Rose model, a RequisitePro project, or a project in Rational Test.


Rules Project

A file that contains rules in compiled format.

If you are using Rational Suite, your project administrator has probably created a repository project, which includes a rules project. If you are not using Rational Suite, you need to create your own rules project.

When you first create a rules project, it is empty. To add a rule to a rules project, import it.You can also delete a rule from a rules project.

The file extension for a rules project is .rsr.


Repository Project

A repository project associates the following items:

one or more Rose models

a RequisitePro database

a Rational Test database

a ClearQuest database

a Synchronizer Rules Project, which contains zero or more Synchronizer rules.

Typically a project administrator or an advanced user creates a repository project using the Rational Administrator. For more information, see online Help in the Rational Administrator. You can create a Repository Project if you are working with Rational Suite.


File > Save Rules Project

Saves the current rules project after you've imported rules or deleted them. You are prompted to save a rules project whenever you take one of these actions or when you've made changes to a rules project and close the Synchronizer.


File > Close Rules Project

Causes the Synchronizer to stop using the current rules project.


File > Import Rules

Loads the text version of a rules file into the current rules project. The rules project stores an imported rule in a compiled format.


File > Delete Rules

Permanently removes a rule from the current rules project, making it unavailable. Does not affect the text version of the rule.


View > Log

Displays a text editor showing details about each item that you have synchronized.


File > file name

Opens the rule project whose name you select.


File > Exit

Quits the Synchronizer.


Actions > Select All

Selects all items in the Item List, so that you can synchronize or disable them.


View > Toolbar

Toggle that determines whether the Synchronizer toolbar is displayed.


View > Status Bar

Toggle that determines whether the Synchronizer status bar is displayed.


Actions > Synchronize Selected Items

Synchronizes the item or items you have selected. When done, the status of the item or items changes to Complete.


Actions > Synchronize All Items

Synchronizes all the items in the Item List. The status of each item changes to Complete.


Actions > Enable Selected Items

Allows you to synchronize an item that is currently disabled. Changes item's status to Pending.

Note: The menu item is enabled only when the status of at least one of the selected items is Disabled. The menu item is disabled when all selected items have status Pending.


Actions > Disable Selected Items

Prevents the item from being synchronized. Changes item's status to Disabled.


Actions > Find Wizard

Displays the Find Wizard so you can add new items to the Item List. Uses the same set of rules you are currently using.

The Item List displays the cumulative results of all the times you've run the Find Wizard since you started the Synchronizer. For example, say you previously ran the Find Wizard and selected Search using selected rules, then chose Rule A. The Item List displayed all items affected by Rule A. If you run the Find Wizard again and choose Rule B, the Item List now displays all items affected by both Rule A and Rule B.


Actions > Find Again

Refreshes the Item List, using the same criteria you last specified with the Find Wizard.


Help > Help Topics

Displays online Help about the Synchronizer.


Help > About Rational Synchronizer

Displays the Synchronizer's version number.


Synchronizer Layout: Toolbar
Toolbar

Provides shortcuts to commonly-used Synchronizer menu items.

Return to Synchronizer Layout.


Synchronizer Layout: Item List
Item List

Displays the items found when you ran the Find Wizard. These items represent proposals to create or update objects in RequisitePro, Rose, or Rational Test.

To sort items in the list, click one of the column headings.

To initiate one or more actions, select one or more items, and synchronize them.

Return to Synchronizer Layout.


Synchronizer Layout: Item Details
Item Details

Shows more information about the single item or the topmost item selected in the Item List:

On the Changes tab, shows all the changes that will occur to the selected item.

On the Item Properties tab, shows the selected item's properties. If the action is Create or Recreate, shows what the properties will be. If the action is Update, shows the properties as they are now (before the update).

On the Linked Item Properties tab, shows the properties of the item on the other side of the link from the selected item.

On the Rule tab, shows details about the rule that will be used by the action.

Return to Synchronizer Layout.


Synchronizer Layout: Status Bar
Status Bar

Displays information about features in the Synchronizer.

Return to Synchronizer Layout.


Rules File

An ASCII text file that contains one or more rules. To use a rule with the Synchronizer, you need to import the rule into a rules project. The file extension for a rules file is .rsd.


Actions

The Synchronizer Item List contains a column for the type of action to perform:

Action	Meaning
Create	Makes a new item and creates a link between the original item and the new item.
Recreate	For an item that was previously created and then deleted, makes the item again.
Update	Changes properties in an item that is linked to an item where changes have occurred.
Delete	For two linked items where one item has been deleted, deletes the other item.
None	A link exists between two items, but there is no action needed at this time.
Link to	Creates a link to an existing item instead of creating a new item.

See also Links


Links

A link maintains a connection between two items.

Establishing a Link at Item Creation

For example, consider a rule that creates a Rose use case for every RequisitePro use-case requirement. When the Rose use case is created, a link is established between the use case and the use-case requirement.

Later, if you change the name of the use-case requirement, and a rule exists that requires the names of these two linked items to be the same, the existence of the link triggers an Update action.

Establishing a Link Manually

In some cases, the Synchronizer may propose to create an item when looking to an item that already exists would be more appropriate. Use the Link to action to establish a link to the existing item and to update properties in the existing item.


Link to action

In some cases, the Synchronizer may propose to create or recreate an item when it is more appropriate to use an item that already exists. For example, you may have started project work before using the Synchronizer, and you may have manually created items that are related to each other. (For example, you may have created both a use case requirement and a Rose use case.) In this case, you want to establish a link between these two items so that when one item changes, updates happen automatically to the other item.

Use the Link to action to establish a link to the existing item and to update properties in the existing item.

1.	In the Item List, right-click on an item to display its shortcut menu.

2.	From the shortcut menu, click Link to action.

The Synchronizer displays a list of available items of the same type as the item it proposes to create. An item is available if it is not already linked to another item. If the list is empty, then there are no available items of this type.

3.	In the list, select the item to which you want to establish a link. Click OK.

The item's Action changes to Link to. Once you synchronize this item, the link is maintained for future updates.


Tips for Working with Rules

This topic provides tips for working with Synchronizer rules:

Planning to write rules

Sample rules

Storing rules

Rule template: what's in a rule

Valid item types and properties

Planning to Write Rules

A Synchronizer rule encapsulates part of your development process. So before you start writing rules, you need to analyze your process. A white paper, Using the Rational Synchronizer, exists to help you. It is available from your Rational technical representative.
return to top

Sample rules

A collection of sample rules is provided with the Synchronizer. Use these samples to help you get started understanding or writing rules. The sample rules are in the directory
install\Rational\common\OutofTheBox\synchronizer rules (where install is the directory to which you installed Rational Suite, by default, c:\Program Files). The Rational Suite Usage Notes, available as a book and on the Rational Solutions for Windows - Online Documentation CD, contains information about each sample rule.
return to top

Storing rules

We recommend that you store your project's rules in the same directory that contains sample rules. Doing so simplifies administration and makes it easier to locate all the rules related to your project. We also recommend that you keep rules under a source control system, such as Rational ClearCase.
return to top

Rule template: what's in a rule

A rule template is provided with the Synchronizer. This template provides a guided tour of a rule. It shows you how to write or understand a rule, line by line. It includes information about rule syntax and specific values to include in rules.

The file is in install\Rational\common\OutofTheBox\synchronizer rules\synchronizer_rule_template.rsd (where install is the directory to which you installed Rational Suite, by default, c:\Program Files)
return to top

Valid item types and properties

The following table shows valid item types and properties (also called attributes) for rules:

Domain	Valid Item Types	Valid Properties
Rational Rose	"Use Case"	Name Documentation Stereotype Rank
	Actor	Name Documentation Stereotype
	Package	Name Documentation Stereotype Global
	"Sequence Diagram"	Name Documentation "Diagram Type" (note1)
	Class	Name Documentation Stereotype "Export Control" Cardinality Space Persistence Concurrency Abstract
Rational Test	Script	Name "Description" Requirement (note2)
Rational RequisitePro	Any requirement type. Type the name of the requirement, not the tag, exactly as shown in the RequisitePro project properties display, on the Requirement tab.	Any attribute for the requirement type, enclosed in quotes if it contains spaces.  (note2)
Note1: A value of 1 means the diagram is a sequence diagram. A value of 2 means the diagram is a collaboration diagram.
Note2: see rule template for more information

return to top


Troubleshooting

This topic helps you solve common problems that may occur when you use the Synchronizer.

Can't log in to RequisitePro

Error returned by server

Synchronizing fails

Item list is blank

Can't log in to RequisitePro

When starting a Synchronizer action that involves logging into RequisitePro, you may see an error message such as "Invalid User ID" or "Login failed". Try this remedy:

1.	Start RequisitePro.

2.	Add the project to the RequisitePro catalog if it is not already in the catalog.

3.	Open the project.

4.	Quit RequisitePro.

5.	Retry the Synchronizer action.

return to top

Error returned by server

Many situations can cause this error. If the problem is that you cannot log in to RequisitePro, try the steps outlined in that section.

Sometimes the Synchronizer displays this message because Rose has left extra processes running. To fix this problem:

1.	Quit the Synchronizer and quit Rose if it is running.

2.	Start the Windows Task Manager.

3.	End each Rose process that is running.

4.	Restart the Synchronizer.

return to top

Synchronizing fails

If you direct the Synchronizer to synchronize items, and the task fails, check for these possible causes:

You are synchronizing to or from a read-only Rose model. This situation might arise if the model is stored in ClearCase but is not checked out, or if someone else has the model open, or if Rose has left extra processes running. If the problem is for another reason, sometimes quitting Rose and restarting it fixes the problem.

You are trying to run rules for a Rose model that has been moved or removed. Because rules contain hard-coded paths, you need to edit the rules to point to the new location.

You can't create an item because its name is either illegal or a duplicate name. In this case, you need to rewrite the rule to address this problem.

return to top

Item List is blank

Sometimes the Item List of the Synchronizer is blank and is colored grey. This is usually because there are currently no items that need updating. One possibility is to rerun the Find Wizard with new search criteria.

return to top